<!--
  #%L
  BlaiseGraphics
  --
  Copyright (C) 2009 - 2015 Elisha Peterson
  --
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
  
       http://www.apache.org/licenses/LICENSE-2.0
  
  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
  #L%
  -->
<html>
  <head>
    <title>org.blaise.graphics package</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
      <p>
          Provides a scene graph component ({@link org.blaise.graphics.GraphicComponent})
          and a tree of {@link org.blaise.graphics.Graphic} objects
          supporting pluggable rendering, mouse actions, selections, tooltips, and more.
      </p>
      <h2>Overview</h2>
      <h3>The Graphics Component and the Graphics Tree</h3>
      <p>
          {@link org.blaise.graphics.GraphicComponent} is the top-level swing component, 
          and works primarily with two classes: 
          a {@link org.blaise.graphics.GraphicRoot} and a {@link org.blaise.style.StyleContext}.
          As might be expected, the first is responsible for storing the shapes and the
          second for drawing the shapes. However, the shapes stored in the {@code GraphicRoot}
          may also provide their own style information.
          Shapes within the {@code GraphicRoot} are stored as 
          {@link org.blaise.graphics.Graphic}s, comprised of:
      </p>
      <ol>
          <li>the graphic object and a means to draw it (in the form of a {@code contains} method and a {@code draw} method),</li>
          <li>a parent for that shape, and </li>
          <li>a tooltip for the shape (parametrized by point),</li>
          <li>a mouse listener for the shape (parametrized by point),</li>
          <li>visibility status ({@link org.blaise.style.VisibilityHint}).</li>
      </ol>
      <p>
          The {@link org.blaise.graphics.GraphicRoot} maintains the shapes that are to be drawn, including both
          the shapes themselves and the order in which they are drawn. This object also listens to
          mouse events from the {@link org.blaise.graphics.GraphicComponent}, which it passes along as a
          {@link org.blaise.graphics.GraphicMouseEvent} to the top-most {@link org.blaise.graphics.Graphic}
          (in terms of draw order) whose parent is a {@link org.blaise.graphics.GraphicMouseListener}.
      </p>
      <h3>Specific Graphics</h3>
      <p>
          Implementing {@link org.blaise.graphics.Graphic} should be straightforward.
          {@link org.blaise.graphics.GraphicSupport} contains much of the code
          required, apart from the {@code draw} and {@code contains} methods.
          {@link org.blaise.graphics.GraphicComposite} groups together several
          {@code Graphic}s, and also has an overridable {@link org.blaise.style.StyleContext},
          which can be used to set a default style for its constituents.
          {@code Graphic}s are typically implemented in one of two ways: either with
          concrete styles, or with styles that are chosen/generated as the
          object is drawn, depending on a "source object". The first are labeled
          by "{@code Basic}" and the second by "{@code Delegating}".
      </p>
      <p>
          Within the package, a few specific {@code Graphic}s
          are implemented, as described in the table below:
      </p>
      <table>
          <thead>
              <tr>
                  <th>Class Name</th>
                  <th>Description</th>
              </tr>
          </thead>
          <tbody>
              <tr>
                  <td>{@link org.blaise.graphics.BasicPointGraphic}</td>
                  <td>A draggable point, rendered by a {@link org.blaise.style.PointStyle}</td>
              </tr>
              <tr>
                  <td>{@link org.blaise.graphics.BasicPointSetGraphic}</td>
                  <td>Several points, rendered by a common {@link org.blaise.style.PointStyle}</td>
              </tr>
              <tr>
                  <td>{@link org.blaise.graphics.BasicShapeGraphic}</td>
                  <td>An arbitrary shape or path, rendered by a common
                      {@link org.blaise.style.ShapeStyle} or
                      {@link org.blaise.style.PathStyle}
                  </td>
              </tr>   
              <tr>
                  <td>{@link org.blaise.graphics.BasicStringGraphic}</td>
                  <td>A string located at a point on the graphics canvas, rendered by a
                      {@link org.blaise.style.StringStyle}
                  </td>
              </tr>     
              <tr>
                  <td>{@link org.blaise.graphics.CustomPointSetGraphic}</td>
                  <td>Several points, with references to source objects, rendered
                      by a {@link org.blaise.style.PointStyle} delegate.
                  </td>
              </tr>        
          </tbody>
      </table>
      <h2>Interfaces</h2>
      Extensible interfaces and abstract classes in the {@code org.blaise.graphics} package are:
      <ul>
          <li>{@link org.blaise.graphics.Graphic} - core graphic object</li>
          <li>{@link org.blaise.graphics.GraphicSupport} - partial implementation of {@code Graphic} with common functionality</li>
          <li>{@link org.blaise.graphics.CanvasPainter} - more general object that paints on a canvas</li>
          <li>{@link org.blaise.graphics.ContextMenuInitializer} - general way to populate a {@link javax.swing.JPopupMenu} given a "focus" object and a "selection" of objects</li>
          <li>{@link org.blaise.graphics.AbstractPointGraphic}</li>
          <li>{@link org.blaise.graphics.AbstractShapeGraphic}</li>
          <li>{@link org.blaise.graphics.AbstractGraphicDragger} - make it easier to interpret drag gestures/events on graphic objects</li>
      </ul>
  </body>
</html>
